home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3dm / old-compression / clOpenDecompressor.z / clOpenDecompressor
Encoding:
Text File  |  1998-10-20  |  11.8 KB  |  199 lines
  1.  
  2.  
  3.  
  4. ccccllll DDDDeeeeccccoooommmmpppprrrreeeessssssssiiiioooonnnn((((3333ddddmmmm))))                                    ccccllll DDDDeeeeccccoooommmmpppprrrreeeessssssssiiiioooonnnn((((3333ddddmmmm))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      clOpenDecompressor, clDecompress, clCloseDecompressor - Decompress a
  10.      video or audio stream
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ddddmmmmeeeeddddiiiiaaaa////ccccllll....hhhh>>>>
  14.  
  15.      iiiinnnntttt ccccllllOOOOppppeeeennnnDDDDeeeeccccoooommmmpppprrrreeeessssssssoooorrrr((((iiiinnnntttt sssscccchhhheeeemmmmeeee,,,, CCCCLLLLhhhhaaaannnnddddlllleeee ****hhhhaaaannnnddddlllleeeePPPPttttrrrr))))
  16.      iiiinnnntttt ccccllllDDDDeeeeccccoooommmmpppprrrreeeessssssss((((CCCCLLLLhhhhaaaannnnddddlllleeee hhhhaaaannnnddddlllleeee,,,, iiiinnnntttt nnnnuuuummmmbbbbeeeerrrrOOOOffffFFFFrrrraaaammmmeeeessss,,,,
  17.          iiiinnnntttt ccccoooommmmpppprrrreeeesssssssseeeeddddBBBBuuuuffffffffeeeerrrrSSSSiiiizzzzeeee,,,, vvvvooooiiiidddd ****ccccoooommmmpppprrrreeeesssssssseeeeddddBBBBuuuuffffffffeeeerrrr,,,, vvvvooooiiiidddd ****ffffrrrraaaammmmeeeeBBBBuuuuffffffffeeeerrrr))))
  18.      iiiinnnntttt ccccllllCCCClllloooosssseeeeDDDDeeeeccccoooommmmpppprrrreeeessssssssoooorrrr((((CCCCLLLLhhhhaaaannnnddddlllleeee hhhhaaaannnnddddlllleeee))))
  19.  
  20. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  21.      _s_c_h_e_m_e         The decompression scheme to use.
  22.  
  23.      _h_a_n_d_l_e_P_t_r      A pointer to the returned handle of the decompressor. Used
  24.                     by subsequent calls to identify the decompressor.
  25.  
  26.      _h_a_n_d_l_e         A handle to the decompressor.
  27.  
  28.      _n_u_m_b_e_r_O_f_F_r_a_m_e_s The number of frames to decompress, which should be a
  29.                     multiple of CL_FRAMES_PER_CHUNK (usually 1 for video).
  30.                     _n_u_m_b_e_r_O_f_F_r_a_m_e_s may also be specified as
  31.                     CCCCLLLL____CCCCOOOONNNNTTTTIIIINNNNUUUUOOOOUUUUSSSS____BBBBLLLLOOOOCCCCKKKK or CCCCLLLL____CCCCOOOONNNNTTTTIIIINNNNUUUUOOOOUUUUSSSS____NNNNOOOONNNNBBBBLLLLOOOOCCCCKKKK.
  32.  
  33.      _c_o_m_p_r_e_s_s_e_d_B_u_f_f_e_r_S_i_z_e
  34.                     The size of the data to be decompressed in bytes.  Used
  35.                     with non-NULL _c_o_m_p_r_e_s_s_e_d_B_u_f_f_e_r to describe buffer length.
  36.  
  37.      _c_o_m_p_r_e_s_s_e_d_B_u_f_f_e_r
  38.                     A pointer to the data to be decompressed.  A value of NULL
  39.                     selects the use of a previously created buffer to supply
  40.                     the compressed data (Implicit Buffering).
  41.  
  42.      _f_r_a_m_e_B_u_f_f_e_r    A pointer to where decompressed frames are to be placed.
  43.                     A value of CCCCLLLL____EEEEXXXXTTTTEEEERRRRNNNNAAAALLLL____DDDDEEEEVVVVIIIICCCCEEEE may be used with some
  44.                     decompressors to indicate a direct connection to an
  45.                     external video or audio destination.  A value of NULL
  46.                     selects the use of a previously created buffer to hold the
  47.                     decompressed frames (Implicit Buffering).
  48.  
  49.  
  50. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  51.      ccccllllOOOOppppeeeennnnDDDDeeeeccccoooommmmpppprrrreeeessssssssoooorrrr opens a decompressor for a given scheme. It is called
  52.      before ccccllllDDDDeeeeccccoooommmmpppprrrreeeessssssss or any call that requires a decompressor handle.
  53.      ccccllllCCCClllloooosssseeeeDDDDeeeeccccoooommmmpppprrrreeeessssssssoooorrrr closes the decompressor after which _h_a_n_d_l_e is no
  54.      longer valid.
  55.  
  56.      ccccllllDDDDeeeeccccoooommmmpppprrrreeeessssssss invokes different buffering models depending on the values
  57.      of the buffer arguments (see CLintro(3dm)).
  58.  
  59.      1. Direct Buffering
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ccccllll DDDDeeeeccccoooommmmpppprrrreeeessssssssiiiioooonnnn((((3333ddddmmmm))))                                    ccccllll DDDDeeeeccccoooommmmpppprrrreeeessssssssiiiioooonnnn((((3333ddddmmmm))))
  71.  
  72.  
  73.  
  74.           If _c_o_m_p_r_e_s_s_e_d_B_u_f_f_e_r and _f_r_a_m_e_B_u_f_f_e_r are non-NULL,
  75.           ccccllllDDDDeeeeccccoooommmmpppprrrreeeessssssss decompresses _n_u_m_b_e_r_O_f_F_r_a_m_e_s from
  76.           _c_o_m_p_r_e_s_s_e_d_B_u_f_f_e_r and stores the result in _f_r_a_m_e_B_u_f_f_e_r.
  77.           _f_r_a_m_e_B_u_f_f_e_r may also be set to CL_EXTERNAL_DEVICE to indicate
  78.           a hardware output destination (currently supported by CL_JPEG_COSMO).
  79.  
  80.      2. Implicit Buffering
  81.  
  82.           If _c_o_m_p_r_e_s_s_e_d_B_u_f_f_e_r and _f_r_a_m_e_B_u_f_f_e_r are NULL,
  83.           ccccllllDDDDeeeeccccoooommmmpppprrrreeeessssssss operates on buffers that have been created
  84.           previously with ccccllllCCCCrrrreeeeaaaatttteeeeBBBBuuuuffff.  The input buffer should be
  85.           filled with calls to ccccllllQQQQuuuueeeerrrryyyyFFFFrrrreeeeeeee, ccccllllUUUUppppddddaaaatttteeeeHHHHeeeeaaaadddd, and
  86.           ccccllllDDDDoooonnnneeeeUUUUppppddddaaaattttiiiinnnnggggHHHHeeeeaaaadddd.  The output buffer should be emptied
  87.           with calls to ccccllllQQQQuuuueeeerrrryyyyVVVVaaaalllliiiidddd and ccccllllUUUUppppddddaaaatttteeeeTTTTaaaaiiiillll.
  88.  
  89.      Direct and Implicit Buffering models may be mixed in one call by setting
  90.      one of the buffer arguments to be non-NULL, and the other to be NULL.
  91.  
  92.      With either model, buffers should be appropriately sized for proper
  93.      execution of ccccllllDDDDeeeeccccoooommmmpppprrrreeeessssssss.  The input compressed buffer should have a
  94.      minimum capacity of CL_COMPRESSED_BUFFER_SIZE bytes.  The output frame
  95.      buffer should have a minimum capacity of CL_FRAMES_PER_CHUNK frames.
  96.      These parameters may be determined by calling ccccllllGGGGeeeettttPPPPaaaarrrraaaammmmssss, after first
  97.      calling ccccllllRRRReeeeaaaaddddHHHHeeeeaaaaddddeeeerrrr to configure the decompressor.
  98.  
  99.      If _n_u_m_b_e_r_O_f_F_r_a_m_e_s is non-negative, ccccllllDDDDeeeeccccoooommmmpppprrrreeeessssssss may consume up to
  100.      CL_COMPRESSED_BUFFER_SIZE * _n_u_m_b_e_r_O_f_F_r_a_m_e_s / CL_FRAMES_PER_CHUNK bytes of
  101.      input data and attempts to produce _n_u_m_b_e_r_O_f_F_r_a_m_e_s frames of output data.
  102.      The call does not return until processing is completed.
  103.  
  104.      If _n_u_m_b_e_r_O_f_F_r_a_m_e_s is specified as CL_CONTINUOUS_BLOCK or
  105.      CL_CONTINUOUS_NONBLOCK then ccccllllDDDDeeeeccccoooommmmpppprrrreeeessssssss continues until either the input
  106.      buffer is marked done, or a call to ccccllllCCCClllloooosssseeeeDDDDeeeeccccoooommmmpppprrrreeeessssssssoooorrrr is made.
  107.      CL_CONTINUOUS_NONBLOCK differs from CL_CONTINUOUS_BLOCK in that the call
  108.      to ccccllllDDDDeeeeccccoooommmmpppprrrreeeessssssss returns immediately while the decompression occurs in a
  109.      separate thread.  These special values should only be used with Implicit
  110.      Buffering.
  111.  
  112.      Multiple decompressors can be open simultaneously. _h_a_n_d_l_e identifies
  113.      which one is being referenced.
  114.  
  115.  
  116. RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEESSSS
  117.      Upon success, ccccllllOOOOppppeeeennnnDDDDeeeeccccoooommmmpppprrrreeeessssssssoooorrrr and ccccllllCCCClllloooosssseeeeDDDDeeeeccccoooommmmpppprrrreeeessssssssoooorrrr return SUCCESS,
  118.      and ccccllllDDDDeeeeccccoooommmmpppprrrreeeessssssss returns the numberOfFrames actually produced or, in the
  119.      case of CL_CONTINUOUS_NONBLOCK, returns SUCCESS immediately.
  120.  
  121.      Upon failure, each routine returns a negative error code.  With some
  122.      schemes, ccccllllOOOOppppeeeennnnDDDDeeeeccccoooommmmpppprrrreeeessssssssoooorrrr returns CL_SCHEME_BUSY if there is a system
  123.      resource (e.g. a piece of hardware) which is in use by another process.
  124.      A return code of CL_SCHEME_NOT_AVAILABLE indicates that the hardware or
  125.      software required by the scheme is not installed on the system.
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. ccccllll DDDDeeeeccccoooommmmpppprrrreeeessssssssiiiioooonnnn((((3333ddddmmmm))))                                    ccccllll DDDDeeeeccccoooommmmpppprrrreeeessssssssiiiioooonnnn((((3333ddddmmmm))))
  137.  
  138.  
  139.  
  140. EEEEXXXXAAAAMMMMPPPPLLLLEEEE
  141.           #include <dmedia/cl.h>
  142.            ...
  143.           /* Open the decompressor */
  144.           clOpenDecompressor(CL_MVC1_SOFTWARE, &handle);
  145.  
  146.           /* Configure the decompressor by reading the header */
  147.           headerSize = clQueryMaxHeaderSize(CL_MVC1_SOFTWARE);
  148.           /* Get the header data from somewhere */
  149.            ...
  150.           clReadHeader(handle, headerSize, header);
  151.  
  152.           /* Allocate implicit input buffer of the required size */
  153.           compressedBufferSize = clGetParam(handle, CL_COMPRESSED_BUFFER_SIZE);
  154.           clCreateBuf(handle, CL_BUF_COMPRESSED, compressedBufferSize, 1, NULL);
  155.  
  156.           /* Decompress a series of frames */
  157.           for(i = 0; i < N; i++)
  158.           {
  159.               /* Keep input buffer full with compressed data */
  160.                ...
  161.               clDecompress(handle, 1, 0, NULL, frameBuffer);
  162.               /* Write the frame to somewhere (such as the screen) */
  163.                ...
  164.           }
  165.  
  166.           /* Close the decompressor */
  167.           clCloseDecompressor(handle);
  168.  
  169.  
  170. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  171.      CLintro(3dm), clReadHeader(3dm), clGetParams(3dm), clCreateBuf(3dm),
  172.      clQueryFree(3dm), clUpdateHead(3dm), clQueryValid(3dm),
  173.      clUpdateTail(3dm), clDoneUpdatingHead(3dm)
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.